清單格式

每個應用程式套件都應包含一個名為 package.json 的清單檔案，其格式為 JSON。本文件將協助您了解清單中每個欄位的意義。

快速入門

以下是極簡清單

{
  "main": "index.html",
  "name": "nw-demo"
}

您只需要至少這兩個欄位即可開始使用 NW.js 應用程式。以下是它們的快速說明

• main：告訴 NW.js 在啟動時開啟與 package.json 相同資料夾中的 index.html
• name：為應用程式提供一個稱為 nw-demo 的唯一名稱

必要欄位

每個套件都必須在其套件描述檔中提供所有下列欄位。

main

• {String} NW.js 啟動時應開啟哪個 HTML 頁面或執行哪個 JavaScript 檔案。

您可以在此處指定 URL。您也可以只指定檔案名稱（例如 index.html 或 script.js）或路徑（相對於 package.json 所在目錄）。

name

• {String} 套件名稱。這必須是一個不含空格的唯一小寫字母數字名稱。它可能包含「.」或「_」或「-」字元。它在其他方面是不透明的。

name 應為全球唯一，因為 NW.js 會將應用程式的資料儲存在名為 name 的目錄下。

功能控制欄位

下列欄位控制 NW.js 應提供哪些功能，以及 NW.js 應如何開啟主視窗。

product_string

• {String} 用於 重新命名 macOS 下的 Helper 應用程式。

nodejs

• {Boolean} 將 nodejs 設為 false 將會在 NW.js 中停用 Node 支援。

node-main

• {String} 指定 node.js 腳本檔案的路徑。它會在 Node 環境中於第一個 DOM 視窗載入前於啟動時執行。

domain

• {String} 指定應用程式所使用的 chrome-extension:// 協定 URL 中的主機。網頁引擎會在您的應用程式與相同網域下的網站之間共用相同的 Cookie。

single-instance

• {Boolean} 指定是否要啟動應用程式的單一執行個體。預設為 true。

預設情況下，NW.js 只允許一個應用程式執行個體。如果您希望允許多個應用程式執行個體同時執行，請將此設為 false。

bg-script

• {String} 背景腳本。腳本會在應用程式啟動時於背景頁面執行。

window

• {Object} 控制視窗的外觀，請參閱下列 視窗子欄位。

webkit

• {Object} 控制 WebKit 的哪些功能應開啟/關閉，請參閱下列 WebKit 子欄位。

user-agent

• {String} 覆寫應用程式發出 HTTP 要求中的 User-Agent 標頭。

下列佔位符可用於動態組合使用者代理

• %name：由清單中的 name 欄位取代。
• %ver：如果可用，則由 manifest 中的 version 欄位取代。
• %nwver：由 NW.js 的版本取代。
• %webkit_ver：由 Blink 引擎的版本取代。
• %chromium_ver：由 Chromium 版本取代
• %osinfo：由您在瀏覽器的使用者代理字串中看到的作業系統和 CPU 資訊取代。

node-remote

• {Array} 或 {String} 啟用在遠端頁面中呼叫 Node。此值控制應為哪些網站啟用此功能。陣列中的每個項目都遵循 Chrome 擴充功能中使用的 比對模式。

比對模式基本上是一個 URL，它以允許的 scheme (http、https、file 或 ftp) 開頭，而且可以包含 '*' 字元。特殊模式 <all_urls> 比對任何以允許的 scheme 開頭的 URL。每個比對模式有 3 個部分

• scheme — 例如，http 或 file 或 *
• host — 例如，www.google.com 或 *.google.com 或 *；如果 scheme 是 file，則沒有 host 部分
• path — 例如，/*、/foo* 或 /foo/bar。路徑必須出現在 host 權限中，但始終視為 /*。

以下是基本語法

<url-pattern> := <scheme>://<host><path>
<scheme> := '*' | 'http' | 'https' | 'file' | 'ftp'
<host> := '*' | '*.' <any char except '/' and '*'>+
<path> := '/' <any chars>

chromium-args

• {String} 指定 chromium (content shell) 命令列參數。

如果您想要使用一些自訂 chromium 參數來散佈應用程式，這將會很有用。例如，如果您想要停用 GPU 加速的影片顯示，只要加入 "chromium-args" : "--disable-accelerated-video"。如果您想要加入多個參數，請用空白分隔每個參數。此欄位也可以在一個參數中採用多個旗標，方法是將它們括在單引號中。

NW_PRE_ARGS 環境變數的值會附加到此欄位的前面。

請參閱 命令列選項 以取得更多資訊。

crash_report_url

• {String} 錯誤報告伺服器的 URL

一旦應用程式發生錯誤，錯誤傾印檔和執行時期環境的資訊就會傳送到錯誤伺服器。傳送方式與在 Chromium 瀏覽器中相同：使用 multipart/form-data 作為內容類型，發送 HTTP POST 要求。理論上，任何 breakpad/crashpad 伺服器都可以處理要求，因為 breakpad/crashpad 在 NW 中的工作方式與在 Chromium 中相同。請參閱 我們的測試案例中使用的非常簡單的伺服器，或 simple-breakpad-server。

要求至少包含下列欄位

• prod - 應用程式清單中的 name 欄位
• ver - 應用程式清單中的 version 欄位
• upload_file_minidump - minidump 檔案的二進位內容
• switch-n - 發生錯誤的處理程序的命令列開關。每個開關都有多個欄位，其中 n 是從 1 開始的數字。

js-flags

• {String} 指定傳遞給 JS 引擎 (v8) 的旗標。例如，開啟 Harmony Proxies 和 Collections 功能

{
  "name": "nw-demo",
  "main": "index.html",
  "js-flags": "--harmony_proxies --harmony_collections"
}

可以在這裡找到支援的 V8 旗標清單：https://chromium.googlesource.com/v8/v8/+/master/src/flag-definitions.h

inject_js_start

inject_js_end

• {String} 相對於應用程式路徑的本機檔案名稱，用於指定要注入視窗的 JavaScript 檔案。

inject_js_start：注入的 JavaScript 程式碼會在任何 css 檔案之後，但在建構任何其他 DOM 或執行任何其他指令碼之前執行。

inject_js_end：注入的 JavaScript 程式碼將在文件物件載入後執行，在觸發 onload 事件之前。這主要用作 Window.open() 的選項，用於在新的視窗中注入 JS。

additional_trust_anchors

• {陣列} 包含 PEM 編碼憑證的清單（例如 "-----BEGIN CERTIFICATE-----\n...憑證資料...\n-----END CERTIFICATE-----\n"）。

這些憑證用作驗證的額外根憑證，允許使用自簽署憑證或由自訂 CA 簽發的憑證連線至服務。

dom_storage_quota

• {整數} DOM 儲存空間配額的兆位元組 (MB) 數。建議輸入您要的兩倍值。

no-edit-menu (Mac)

• {布林值} 預設的 編輯 功能表是否應在 Mac OS X 上停用。預設值為 false。僅在 Mac OS X 上有效。

視窗子欄位

大多數視窗子欄位預設由 window.open() 或連結（<a target="_blank">）開啟的子視窗繼承。非繼承子欄位的例外清單如下。它們將設定為開啟視窗的預設值

• 全螢幕 -> false
• 資訊亭 -> false
• 位置 -> null
• 可調整大小 -> true
• 顯示 -> true

所有視窗子欄位都可以使用 new-win-policy 事件 覆寫。

id

• {字串} 用於識別視窗的 id。這將用於記住視窗的大小和位置，並在稍後開啟具有相同 id 的視窗時還原該幾何形狀。 另請參閱 Chrome 應用程式文件

title

• {字串} NW.js 建立的視窗的預設標題，當應用程式啟動時您想要顯示自己的標題時，這非常有用。

width

height

• {整數} 主視窗的初始內部寬度/高度。

toolbar

• {布林值} 是否應顯示導覽工具列。

icon

• {字串} 視窗圖示的路徑

position

• {字串} 可為 null 或 center 或 mouse，控制視窗放置的位置

min_width

min_height

• {整數} 視窗的最小內部寬度/高度

max_width

max_height

• {整數} 視窗的最大內部寬度/高度

as_desktop (Linux)

• {布林} 在 X11 環境下顯示為桌面背景視窗

resizable

• {布林} 視窗是否可調整大小

請注意，如果在 OS X 上將可調整大小設為 false，且將框架設為 true，使用者仍然可以將視窗設為全螢幕。將全螢幕設為 false 以停用全螢幕控制項。

always_on_top

• {布林} 視窗是否應始終保持在其他視窗上方。

visible_on_all_workspaces (Mac & Linux)

• {布林} 視窗是否應同時顯示在所有工作區（在支援多個工作區的平台上，目前為 Mac OS X 和 Linux）。

fullscreen

• {布林} 視窗是否為全螢幕

請注意，如果在全螢幕中也將框架設為 false，將會防止滑鼠在螢幕的最邊緣被擷取。如果全螢幕也設為 true，您應避免啟用它。

show_in_taskbar

• {布林} 視窗是否顯示在工作列或 Dock 中。預設為 true。

frame

• {布林} 將其指定為 false 以使視窗無邊框

請注意，如果在全螢幕中將框架設為 false，將會防止滑鼠在螢幕的最邊緣被擷取。如果全螢幕也設為 true，您應避免啟用它。

無邊框應用程式沒有標題列，供使用者按一下並拖曳視窗。您可以使用 CSS 將 DOM 元素指定為可拖曳區域。

.drag-enable {
  -webkit-app-region: drag;
}
.drag-disable {
  -webkit-app-region: no-drag;
}

show

• {布林} 如果您希望您的應用程式在啟動時隱藏，請將其指定為 false

kiosk

• {Boolean} 是否使用Kiosk模式。在Kiosk模式下，應用程式將會全螢幕顯示，並嘗試防止使用者離開應用程式，所以您應該記得在應用程式中提供一種離開Kiosk模式的方法。此模式主要用於公開展示

transparent

• {Boolean} 是否開啟透明視窗模式。預設為false。

在 CSS 中使用 rgba 背景值來控制透明度。使用命令列選項--disable-transparency來完全停用此功能。

對透明區域的「點選穿透」有實驗支援：將--disable-gpu選項加入命令列。

WebKit 子欄位

double_tap_to_zoom_enabled

• {Boolean} 使用 2 根手指在 Mac 上雙點按一下來啟用縮放，預設為 false。

plugin

• {Boolean} 是否載入外部瀏覽器外掛程式，例如 Flash，預設為 true。

其他欄位

Packages/1.0 標準指定了package.json應該提供的許多其他欄位。目前我們並未使用這些欄位，但您仍然可以提供。